@opentelemetry/api

What is @opentelemetry/api?

The @opentelemetry/api package provides a set of APIs to instrument JavaScript applications for telemetry purposes. It allows developers to collect traces and metrics from their applications, which can then be exported to various observability backends for monitoring and analysis. The API is designed to be minimal, extensible, and vendor-neutral.

What are @opentelemetry/api's main functionalities?

Tracing

This feature allows the creation and management of traces to monitor the flow of a request through various services. The code sample demonstrates how to create a tracer, start a new span, and then end the span.

const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('example-tracer');
const span = tracer.startSpan('example-span');
span.end();

Context Propagation

This feature enables the propagation of context information across asynchronous operations or service boundaries. The code sample shows how to associate a span with a context and execute a function within this context.

const { context, trace } = require('@opentelemetry/api');
const currentContext = context.active();
const span = trace.getTracer('example-tracer').startSpan('example-span');
context.with(trace.setSpan(currentContext, span), () => {
  // Your synchronous or asynchronous operation here
  span.end();
});

Metrics

This feature supports the collection of quantitative measurements of operational events, such as request counts. The code sample illustrates how to create a meter, define a counter metric, and increment the counter.

const { metrics } = require('@opentelemetry/api');
const meter = metrics.getMeter('example-meter');
const counter = meter.createCounter('example-counter');
counter.add(1);

Other packages similar to @opentelemetry/api

jaeger-client

Jaeger client is a package for tracing applications and sending the traces to Jaeger, a distributed tracing system. Unlike @opentelemetry/api, which is designed to be vendor-neutral and supports multiple backends, jaeger-client is specifically tailored for integration with Jaeger.

prom-client

Prom-client is a package for collecting metrics in Node.js applications and exporting them to Prometheus, a monitoring and alerting toolkit. While @opentelemetry/api provides a more general approach to metrics collection compatible with various backends, prom-client is specifically focused on Prometheus integration.

README

OpenTelemetry API for JavaScript

This package provides everything needed to interact with the OpenTelemetry API, including all TypeScript interfaces, enums, and no-op implementations. It is intended for use both on the server and in the browser.

Basic Use

API Entry Point

API entry points are defined as global singleton objects trace and metrics which contain methods used to initialize SDK implementations and acquire resources from the API.

• Trace API Documentation
• Metrics API Documentation

const api = require("@opentelemetry/api")

/* Initialize TraceProvider */
api.trace.initGlobalTracerProvider(traceProvider);
/* returns traceProvider (no-op if a working provider has not been initialized) */
api.trace.getTracerProvider();
/* returns a tracer from the registered global tracer provider (no-op if a working provider has not been initialized); */
api.trace.getTracer(name, version);

/* Initialize MeterProvider */
api.metrics.initGlobalMeterProvider(meterProvider);
/* returns meterProvider (no-op if a working provider has not been initialized) */
api.metrics.getMeterProvider();
/* returns a meter from the registered global meter provider (no-op if a working provider has not been initialized); */
api.metrics.getMeter(name, version);

Application Owners

Application owners will also need a working OpenTelemetry SDK implementation. OpenTelemetry provides working SDK implementations for web and node for both tracing and metrics.

Simple NodeJS Example

Before any other module in your application is loaded, you must initialize the global tracer and meter registries. If you fail to initialize a provider, no-op implementations will be provided to any library which acquires them from the API.

const api = require("@opentelemetry/api");
const sdk = require("@opentelemetry/node");

const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');

// Initialize an exporter
const exporter = new JaegerExporter({
  serviceName: 'basic-service'
});

// Create a provider which we will configure as the global tracer provider
const provider = new sdk.NodeTracerProvider();

// Configure span processor to send spans to the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

// Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
api.trace.initGlobalTracerProvider(provider);

// your application code below this line

Library Authors

Library authors need only to depend on the @opentelemetry/api package and trust that the application owners which use their library will initialize an appropriate SDK.

const api = require("@opentelemetry/api");

const tracer = api.trace.getTracer("my-library-name", "0.2.3");

async function doSomething() {
  const span = tracer.startSpan("doSomething", { parent: tracer.getCurrentSpan() });
  try {
    const result = await doSomethingElse();
    span.end();
    return result;
  } catch (err) {
    span.setStatus({
      // use an appropriate status code here
      code: api.CanonicalCode.INTERNAL,
      message: err.message,
    });
    span.end();
    return null;
  }
}

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us on gitter

License

Apache 2.0 - See LICENSE for more information.

Changelog

0.4.0

Released 2020-02-05

:rocket: (Enhancement)

• opentelemetry-api
  • #727 Api separation (deprecate opentelemetry-types)
  • #749 chore: rename registry to provider

:sparkles: (Feature)

• opentelemetry-plugin-http
  • #719 feat(plugin-http): sync. specs for statuscode
• opentelemetry-exporter-jaeger
  • #735 feat: decode jaeger header
• opentelemetry-plugin-user-interaction
  • #658 feat: plugin user interaction for web

:books: (Refine Doc)

• #689 Add benchmark README and latest numbers
• #733 chore: add instruction for pg-pool plugin
• #665 docs: add ioredis example
• #731 Update Stackdriver exporter example

:bug: (Bug Fix)

• opentelemetry-exporter-jaeger
  • #715 fix: unref jaeger socket to prevent process running indefinitely
• opentelemetry-plugin-ioredis
  • #671 [ioredis plugin] fix: change supportedVersions to >1 <5